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is zocumeant deszribos tha use of TISSOO assembly language 
on Extanded Basic 2n the TI S974 Homa Computer. t 
an introduction to the architecture of tha 99/4, and to 
portions of the design o? Extended Basic. The mininum 
configuration required to run 9900 code is a 99/4 console, 
r, a Memory Exsansian perirheral, end an Extended Basic 
ina language modulis. à cassette tape player/recorder or 
disk unit are required to make use of all available 


ŞED ende is written and assemblea? on a host TI 7990 
uter and downloaded to the "9/4 diskette. The file 
Jtility 28 the Terminal Emulator II command module is 
or tnis procedure I? that is not avaiia3b:e, the object 
i bə entere jirectiu bu using a small Extended Basic 
to copy From keyboard to dis 
OPEN #1 "DZbi.FRZG A", GUTPUT, DISPLAY, FIXED 5° 
ACCEPT As 
Ir At="." THEN CLOSE 1 STOF 
PRINT #1: 4S 
GOTO 200 
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Memory Architecture o? the 79/4 


Tha 9974 has aversl independent address spaces, which are 
through memory mapped 1/0 in the primary (CPU? address 





Most of the RAM within the consoles is in the VDP (Video 


Dispiag Processor} spa». This memory is accessed through the 
VBP chip, and therefore cannot contain 79900 code cr workspaces. 
VEE RAM is used for the screen image, character pattern tables, 
c23i1or tables. etc. When using Extended Basic with an Expansion 
Raf peripneral. the VDP RAM is also used to hold the program's 
symool table, valua stack, and string space. VDP RAM is accessed 
Dy writing the target address to CPU address >5C02 (least- 
significant byte first). and تی سس‎ data From address 28800 
ar writing data to address leco The address written to 03ء‎ 
should have 3400C added to it if usu wish to write. Access to 
VPD RAM is in auto-increment mods, so that you only need to send 
ons address to read or write a block of data. VDP RAM consists 
2f ik bytes: with addresses 20000 to >3FFF (or 74000 to 27FFF 
for write moda}. 

The Screen is at VDP Bam locations rO to >2FF. The first 32 
bytes are the characters on the first Line, the next 32 the 
zharscters on the second line, etc. 

CAUTION 
The characters on the screen are not in the 
standard ASCII code. Each character has an 
offset af 260 added to it. Thus the 
character "AU is represented by a ai, 
instead 5? by a 241. If you want to display 
a string on the screen. you must add 60 to 
each byta before writing it to the screen 
The character pattern table begins at VDF location 2400. The 


locations 5400 to 2407 contain the bits for tha character SPACE 
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MamoTy Srınizecsure or the 97/4 

503. These are initialized to all O's. 

i to display as biank. Locations 7408 to 
Sesam Wt (ASCII >21 or screen 81). etc. 
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| Dynamic Sym Tab and FSB‘s : 


AAA Ao nn +‏ - - --- - -- - - - - - کے کا AAA A‏ 
H String Space t‏ 
+ وہ ہے es‏ ن a‏ ت ات و ا :س س 
t (fres! t‏ 
+ کا س س ت - -- - - - - -- - - - - - - - - - - - - --=+4 | -=- 


+o ee - -- - -- - - - > -- - - - - -- -- - --- + 
D Edit-Recall Buffer i 
+=--- -- A AAA A A AAA AAA o + 
i Crunch Buffer : 
de e -- -- - - -- - --- - -- - - - - - - س ا ت‎ + 
i Color Tables i 
کے سم کش سب کے ات کے ےت سے ہے سے ہی‎ RER SEE EEE BEE E 
H Sprite Velocity Block i 
tooo ——————————--— ---- - - - - -- + 
i Character Tabies 


GPL Interpreter 
Roll-sut Area 


i BASIC Temporaries i 
+- -- - - - - -- - عم اہ لہ سم‎ wee سا ا ت ا ت ا ا س سک س ا‎ + 
i Sprita Attribute List i 
+--- - - -- - - - > اعدم مہ اہ لم - ا‎ ————————— -+ 
i Screen i 
+------- - - - - - - - -- - - - - --- - A سا ا‎ + 


VDP RAM Usage by Extended 
Basic when Memory Expansion 
is Present. 


6) 


2.2 Internal RAM 

The only directly adiressabie CPU RAM inside the console is 
at acdresses 26300 zo جن‎ 182300 to 258313 will be used to 
sius3ort oarameter passing to machine language subprograms. This 
wili be discussed later under CALL LINE. The rest is used by 
Extanded Basic for Pointers into VIP REM (2 y. top-of-stack) and 
giosal oarameters (e.g OPTION BASE O or 1, ON ERROR transfer 
address, etc. }. 


2.3 Expansion RAM 


The Memory Expansion peripheral has two blacks of memory, a 
ZAV block from address 24000 to >FFFF, and an EX biock from 22000 
Ego IEEE Extended Basic uses the 24K block for storage of the 
Sasic program, lins number table, and numeric variables. The 8k 
blest: may be used For machine language subprograms. It is 
cossible to use a part of the 24K block for machine language as 
well. Basic allocates space to itself from the high end of 
memnarg. so you may place machine language code and data at the 
low end. In order to load code here, it should be assembled in 
absoiute mode (e.g. ADPG +4000) rather than relocatable. 4 
painter to the beginning of free (unallocated? memory may be 
found in location 722286 (RAMFRE). 


24 Structure of the ALC biock 


The Routine Name Tadle consists of B byte entries; 6 bytes 
37?  subprogram name Ffoallowed by 2 bytes o? entry address. The 
first entry is placed at location >39FFE->3FFF As described below, 
thas2 entries are taken from the S- and &- tags of an object 
fiie The Last Free Address (LFA pointer is initialized to 
240200. tt points st the first used byte in the Routine Name 
Tatia when the name table is not empty. The First Free Address 
(FEA: pointer is initialized to the first unused location after 
the utilities and points to the next free byte after subprograms 
havea been loaded. FFA % LFA are loaded into RAM locations 28308 
% BIO (CPU RAM: respectively at the start of a LOAD from a 
fils. So if absolute code is to change the values of FFA & LFA 
it must modify locations 758208 % >E304. 
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are included in Extended Basic which 
z and 1ء قہ‎ 182 language 


2.1 CALL INIT 

INIT initializes tha ¿ree space and entry name table 
poinitars, and transfers the standard assembly language support 
package from GROM to RAM An exception will occur if INIT is 
zall2d with no erpansion RAM attached, or with the expansion RAM 
mot powered up. 
3.2 C&L PEEK Cadaress, var=1l. ¿var-2,... 1; 

PEEK is used to directiy read bytes of CPU RAM into Basic 
variables. The address is a decimal value from -22748 to 
32757, representing two byte addresses. Addresses above >7FFF 
are writien as negative numbers, treating the tuo byte quantity 
as s tuo's complement integer. (i. e. to access an address above 
32747, subtract 65536 from it.) 


CAUTION 


Because of tha autoincrement 
sone memory mapped address sp S: PEEKing 
certain addresses will have undesirable side 
effects. In particular, truing to read from 
the ROM containing Extended Basic can cause a 
systam crash. 


3.3 CALL LOAD(object-1,i0bject-2,... 3) 


The LOAD routine is used to load an assembly language object 
file or direct data into the RAM expansion for iater execution 
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with the LINK routine. Each of the object arguments must be 
sizher as string 2xpression or 3 list of integers. The string 
Brorassion should evaluate to the name of a file containing a 
Ol object program. The List of integers (poke list) should be 
sn address between -Z22725 and 

32727 (see PEEK), followed by a list cf integers to be used as 
ors byte of data each. These will be loaded into consecutive 
locations, starting sT the given address. an empty string ce) 
may be used to separate the last byte of one poke list and the 
starting address of the next. The address in a poke list is 
absolute and the data is non-relocatable. if you load a routine 
directly with a poke list, you should also load a name table 
entry, $590 that the routine may be found by CALL LINK described 
below. when poking data. space is not automaticaliy reserved. 
The poke  orocedure written oy the user can do this by modifying 
tha FFA and LFA pointers. However this cannot be dene without 
reading (peeking? them. The FEEK routine can be used to read the 
pointers before modifying them. 

The file will be opened and read by the LOAD routine 
Reliocatab!e code will be loaded at the first available address. 
Room will be reserved for the ALC routine according to the length 
spacified in the "O-tag" field in the object file. Absolute code 
will be loaded at the absolute address specified in the object 
codes. 

CAUTION 

Absolute code will be loaded at whatever 
address is specified in the object code. 
Space will not be reserved in the RAM 
expansion for that code. Space will hbe 
reserved at the first available address for 
the length specified in the “O-tag" field. 
The assembly language programmer must take 
extreme care that absolute code is really 
needed and that it will work properly 

Loading data into memory already being used 
by Extended Essic can, of course, cause a 
System crash. 

The first ALC module loaded will load starting immediately 
aftar the utilities. The First Fres Space pointer will be 
initialized to that address by the CALL INIT. Relocatable code 
will be relocated to the starting load address. Whenever a “O- 


tag" is encountered the starting load address is updated from the 
First Free Space pointer and the First Free Space pointer has the 
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nalsle length added to it. With this scheie modules are loaded 
serisllg from the lowest address. individuai modules cannot be 
deisted from memory. The whole memory may be cleared with a CALL 
INIT 


The object tags generated sy DEF statements (S- and &-tags) 
are used to define ALC routines which can be called by name from 
BASIC. The 5- and á- tags contain the DEFed name and address. 
These names and addresses sre placad in the Routine Name Table 
starting at the highest memory address (23FFF) and working down. 
These entries are 5 bytes each. 

Assembly language code may be loaded from any device which 
٭‎ ں٥٥‎ ت٣٥‎ sequential display files af fixed length 80. 
Principally the load device will be a fila on the floppy disk, 
however, the audio cassette recorder may be used 


In order for the object code files to load properly the 
following conventions must be followed: 


Program: No secondary references (SREF, LOAD? or 
segments (PSEG, DSEG, CSEG?) sre allowed. 


Assembly: The SYMT (symbol table) option cannot be used. 


Linking: Following is the correct form for the Link Editor 
Control File: 


TASK  task-name 
PARTIAL 

NOTGLOBAL Label... 
INCLUDE  file-name 
INCLUDE file-name 


u at t€ u 


If only one file is baing used then it does not have to be 


inked. 


The PARTIAL command retains the entry points (5- and 6-tags) 
which are used by the BASIC subprogram LINK as entry points. 
Libraries may ba used in the link edit. 


s the labels listed to be 
Fils. They will still be used 
is would include any labels 

be used as entry points from 


The NOTGLOEAL command cause 
excluded from the Linked Object 
during the Link process though. T 
that were DEFD but are not t 
Extended Basic. 
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ff the DEFS or REFS macros are used then all of those labels 

wiii have tc 5e included in a NOTGLOBAL command, otherwise they 

would de placed into fhe Routine Name Table (and be available as 

entry points from Extended Dasic?. A skeleton Link Edit Control 

ilis is avallabi2 oan file: . HCDEV., ALCL IN4 which contains the 

NOTGLOBAL commands for the labels DEFD by 9 Specifically 
fiie .HCDEV. ALCLINK should contain: 





VEPWA, /DPWD, YDPRDB, VEPSTA, FAC, SUEWS, GPLWS 

NOTGLOB URGE Di ee 

VMEW, VSBR, VMBR. VWTR, ERR, FADD‏ ۷58۷ وی 

Bc AN FSUB, FMUL, ۲ SA DD, SSUB, SMUL., ED IV, CSN 
TGLOBAL CFI,FCCHP, NEX COMPCT, GETSTR. MEMCHK, VPUSH 

ENG ASSEN, ONS UPOP, CIF, SCROLL, VGWITE, GVWITE 

END 


-~ n 


3.4 CALL LINKistring-expressiıon, [psarametar-list)) 


The LINK subprogram passes control from a GASIC program to 
an assembly language subprogram. The string-expression should 
avalvate to 1-5 characters, which is the name of an assembly 
language routine. The parameter-list is an optional list of 
parameters, passed using the same conventions as parameters 
passed to an Extended Basic subprogram. The LINK subprogram 


perfzrms the following actions: 


Evaluats the ALC subprogram name and its length (1-6), 
and push the FAC entry on the value stack 


t4 


m 


Build the ALT argumant list consisting of stack and 
identifier table entriss 


3. Move the sub-name from string space to the FAC entry 
and transfer control over to the utility code 


4. On return, branch to an error routine if an error has 


been detected; otherwise, clear the stack and return 
normally 


The arguments are passed to the ALC subprogram through the 
stack in VDP RAM and the identifier list in CPU RAM. The 
identifier list consists of the following: 


addrass 
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i. (78200 = PESCF ? Argument identifiers (one byte each; 
maximum o? 16; 


z. ) 222٤0 + Old value stack pointer. 

c. B13 ) Number o? arguments 

2 (258314 + Temporary storage space for subroutine 
name 

There are 4 types of arguments supported. 

M Numeric Expression - The identifier will contain a O. 
The eight byte stack entry will contain the value of 
the numeric 2xpresslön. The first byte is the 
exponent, in excess-44, radix 100 notation. The other 
seven bytes contain O to 97, for radix 1CO digits. If 
the number is negative, the first word (tuo bytes)? IS 
negated. 

Z. String Expression - The identifier will contain a 1. 
The string entry will contain: 

a. Bytes 0-1: 001€ 

b. Byte =: L65 (the string tag! 

c. Bytes 4-5: Pointer to the value of the string in 
VPD RAM. 

d. Butes 6-7: Length of the string. Byte à should 
always ba zero, since the maximum string length 
is 255 characters. 

3. Numeric variable - This itam will either be a numeric 
variable or a numeric array element. The identifier 
list will contain a 2 for this entry. The string will 
contain: 

a. Bytes O-1: Pointer to the varaible’s symbol 
table entry in VDP RAM. 

b. Byte =: zero 

c. Bytes 4-3: Pointer to the eight odyte value of 
the variable, in Expansion RAM. 

4 String Variable - This item will either be a string 
variable or a string array element. The identifier 
list will contain a 3. The stack entry will contain: 
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a. Bytes 6-1: Pointer to the variable’s symbol 
table entry in VDP RAM. 


5. Byte 2 اود‎ 

c. Bytes 4-3: Pointer to the string's value in VDP 
RAM 

d. Butes &-7: String lenath. 

5. Numeric Array - This entry results from an argument of 
the form Ai} or AG) etc. This is used so that s 
subprogram may manipulate an entire array. The 
identitier list will contain a 4 for this entry. The 


string entry will contain: 


a. Bytes 0-1: Pointer to the array’s symbol table 
entry in VDP RAM. The byte pointed to will 
contain the number of dimensions of the array in 
the least significant three bits. 


b. Byte 2: zero. 


c. Bytes 4-3: Pointer to the array’s value space in 
VDP RAM. The value space will have two bytes for 
each dimension, indicating the maximum index for 
that dimension, and tuo bytes for a pointer to 
the first element's eight byte value in Expansion 
R AM. The values are stored in row-major order. 
(i.e. the first index varies tne fastest.) 


ir 


String Array - Similar to the entry for a numeric array 
except the identifier list will contain a S and byte 2 
af the stack entry will contain 695. The value space 
for a string array will contain two bytes for each 
dimension, indicating the maximum index, followed by 
two bytes for each array element, which is used 35 a 
pointer to the element’s value string in VDF RAM. 


Any argument that can be passed as a variable will be passed as 
such rather than as an expression. 


The assembly subprogram is called through a Name Link 


Routine written in assembly language and loaded with the 
utilities. The Name Link Routine looks up the name of the 
routine to be called in the Routine Name Table and branches to 
the ALC subprogram. The Name Table is searched from the lowest 
address up so that if tuo routines are LOADed with the same name 
then the second one loaded will be used. The name of the routine 


to ba called will ba placed in FAC blank filled to 6 characters. 
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nzaertaze with extended Basic 


if he name supplied by the user is greater than 6 characters 
then an error will result. This error will be detected in GPL 
before the XML It the Name Link Routine cannot find the name in 
fas tabie then it will return with the GPL condition bit set to 
indicate that error 
The Name Link Routine will branch fo the ALC routine with a 
direct 9960 code branch. When the ALC routine is called from the 
INA routine the workspace will be at 78550. The ALC routine 


H 

Myst retain Rit. R13, Rid, and R15 in tnat workspace and return 
to the GPL interpreter with an RT instruction. Normally the ALC 
routines will have their own workspaces and will return to GPL 
wita a LWPI >BSEO followed by a RT. The macros ENTRY and RETURN 
described below ars useful to handie this 


The ALC subprogram can assign neu values to numeric or 


string  variablss or to elements of numeric or string arrays with 
utilities provided by the system. These utilities are described 
in a later section. 


When the ALO routine returns to LINK the stack must be 
zleared. The entries on the stack must be individually popped to 
release any temporary strings 
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SECTION 4 
Utilities 

The utility routines are provided for use by assembly 
3 


language subprograms to access machine resources and to interface 
with the BASIC interpreter. 


Utility subroutines are provided in the RAM expansion so 
thar ALC subprograms can be shorter and more machine independent. 
The utility routines are called with BLWP instructions and use 
registers to pass arguments. 


41 VEP Access Utilities 


Several utilities are provided for access to the Video 


Display Frocessor. Macros (see below) are also provided when 
sp=23 is important. Ganerally using the utilities instead of the 
macros will save code space. 


All parameters are passed through the calling program's 
workspace registers. 


VDE Single Bute Write. This routine writes the single byte value 
in the most significant byte of register 1 to the VDP RAM address 
indicated in register O. The routine is accessed by a BLWP 
@VSBEN. 


VBE Multiple Byte Write. This routine writes the number of bytes 
indicated in. register 2 from the CPU RAM buffer pointed to by 
register 1 to the VDF RAM buffer pointed to by register O. The 
utility is called with a BLWP @VMBW. 


VDP Single Byte Read. This routine reads a single byte from the 
VBP RAM address indicated in register O, and places it in the 
most significant byte of register 1. The routine is called with 


a BLWP ) 1. 


VEE Multiple Bute Read. This routine reads the number of bytes 
indicated in register 2 from the VDP RAM buffer pointed to by 


register O, and places them in the CPU RAM buffer pointed to by 
register 1. The utility is accessed by a BLWP ۰. 
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VOR Write to Register. This routine writes the single byte vaiue 
in the least significant byte of register O to the VDP register 
indicated in the most significant byte of register O. The 
routine is called with a BLWP @VWTR. 


4 2 Argument passing utilities 


Numeric Assignment. A utility is provided to allow a value to be 
assigned to a numeric variable passed as an argument. The 
floating point variable to be assigned will be in FAC and the 
argument number will be passed in Ri (Full word). The utility is 
called with a BLWF GNUtASG. I? the requested argument is not a 
numeric variables then the routine will return to GPL with the GPL 
condition bit set 


For assignments to a simple numeric variable RO must contain 


a rero. For an assignment to an array RO will contain the array 
elsment number. The assignment utility will test for legal 
bounas on the element number. With OPTION BASE O the element 
number must range from O to (maximum number of elements ~ 1). 


With OPTION BASE 1 then the element number must range from 1 to 
Maximum number of alaments. 


String Assignment. A utility is provided to allow a string to be 
assigned to a string variable passed as an argument to the 
subprogram. The utility does the following: 


1. Allocates space for the string in VDP RAM. 


2. Copies the string into VDP RAM. 


t) 


Assigns the string to the selected varaible 


4. Fixes up the original argument stack entry to point to 
the new string. 


The string to be assigned is constructed by the ALC routine in 
the RAM expansion. The first byte of the string is the length of 
tha string. The assignment utility is called with the string 
address in register 2 and the argument number in register 1 (full 
word). The utility is called with a SLWP @STRASG. If the 
argument specified is not a string variable then the routine will 
return to GPL with the GPL condition bit set 


For assignments to a simple string variabla RO must contain 


a zaro. For an assignment to an array RO will contain the array 
element number. The assignment utility will test for legal 
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Bounds on the slament number. With OPTION BASE O the element 
number must range from G to (maximum number of elements - 1). 
With OPTION BASE 1 then the element number must range from 1 to 
maximum number of elements. 


get Numeric Pasramster. A utility is provided to fetch the value 
of 3 numeric parameter. Register 1 contains the parameter 
numbar. If the parameter is an array, register 0 contains the 
element number, otheruiss, register C contains O. The value of 
the numeric parameter is returned in FAC. The utility routine is 
accessed by a BLWP GNUMREF. 


Get String Parameter. This utility is used to fetch the value of 
a z’ring parameter. Register 1 contains the parameter number. 
Ir “he parameter is an array, register G contains the element 
number, otherwise, register O contains C Register 2 contains 
tna address of a CPU RAM buffer. Upon calling the utility, the 
first byte of the buffer must contain the buffer length. If the 
string will not fit in the buffer, an error condition occurs. 
Othzrwise, the string is returned in the buffer following the 
lenı“h byte. The length byte will be modified to reflect the 
actual length of the string. This utiiity is called with a BLUWP 
RSTRREF. 


4.23 Extended Utilities 


. 


Utilities built into the ROM of the 79/4 console and the 
ROMs in Extended BASIC may be accessed as foliows: 


BLWP @XMLLNA 
DATA wroautine-name> 


Some routine names will BL through the XML tables in Extended 


BASIT While others will call varioys console ROM routines. 
Routine names are defined in the EGUS macro and are li 


FADD Floating point add. 

FZUB Floating point subtract. 
FMUL Floating point multiply 
FOIV Floating point divide. 
SACD Floating point stack add. 


seus Floating point stack subtract. 
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SMUL Floating point stack multiply. 
SEIV Floating point stack divide 

CoN Convert string to number 

CFI Convert floating point to integer 


FCOMP  Fioating point compare. 

COMPCT Perform garbage collection 

SETSTR Allocata space from string space. 

MEMCHK Allocate memory for PAB 

VPUSH Push a value on the floating point stack. 


ASSGNV Assign value to variable. 


CNS Convert number to ASCII string. 
VPOP Pop a value from the stack. 
CIF Convert integer to Floating point 


SCROLL Scroll the screen. 
VGWITE Transfer VDF memory to expansion RAM. 


GVWITE Transfer expansion RAM to VDP memory 


Kaubaard Scan. The equivalent of a GPL scan instruction can be 
done by a BLWP @KSCAN. The GPL status bit msy be tested on 
return with 3 compare ones corresponding (COC) instruction. The 


GPL status register is in location 785C7 


/ H / GT “COND “CARRY” OVF ؛ر‎ O 7 O / O fF 


Bit 5 will be set if a key was found pressed, and it was 
different from the key found pressed on the last call to KSCAN. 
The program must select keyboard device by placing a byte in 


location 728374. The meaning of this byte is the same as the key- 
unit in the CALL KEY subprogram. You may read the ASCII value of 
the key pressed from location 8373. Joystick Y and X positions 


ars in locations 28276 and 722377. respectively 
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Er-sr Reporting. The assembly language program may report any 
asr1izing Extended BASIC error or warning message upon returning 
El 
d 


to 06S ASIC. This is done with the error reporting utility. The 
program must isai RO with the appropriate error code and then 
Sin? GERR. Tas definitions of the error codes may be included in 
tha standard macro file, described in a then next section. 
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Macros- 


Assembler macros are provided to make programming in the TI 
Şer environment =351er. The macros are used in a 7900 assembly 


4, 


with a COPY of the tile given in Appendix &. 


.1 EQUS 


Ut 


This EGUZ macro is used to define global equates for the ALC 
subprogram. Included is the definition of a workspace and 
equates for the various hardware resources. Equates for the 
addresses of the utility branch table entries are also provided. 


5.2 EQUDEES 


This macro is similar to EQUS, but contains the addresses 
aporopriate for use from a debugger station. The addresses of 
routines in console ROM are different, since extra code has been 
incsiuded there to support breakpoints 


3.3 ERREGU 


This macro provides equates for ail the various Extended 
BASIC error and watning messages. 


5.4 Ders 

The DEFS macro is used when several ALC routines will be 
linked together to form one ALC subprogran. This macro causes 
the definitions in the EQUS macro to be global during the link 
edit. 
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“Macros 


whem several نا ام‎ routines will be 


The REFS macro 13 usad 
linkad together to form one ALC subprogram. This macro allows a 
routine to reference the equates defined in the DEFS macro 
S.S ENTRY 

The ENTRY macro is written as ENTRY label where label is the 
entry point name cf the routine. This macro defines the entry 
point with the sperified, defines a workspace for the subprogram, 
and loads that warkspecs 


$.7 RETURN 

The RETURN macro is used to return from the ALC subprogram 
En SASIC. This macro requires that the program contain the one 
byte value ZC at the ladal “C2o". This value is used to reset 
the GPL condition bit before returning to BASIC. If this is not 


done, false error reporting can occur 


5.5  VDPADR 


This macro loads the VDF address with the specified 
workspace register. 


$5.9" VDPWD 

The VDPWD macro is used to write one byte o? data from the 
most significant byte of a register. Two VDPWD macros cannot be 
32d without other code between them or the accesses will be too 
fast for the VDP. 


$.10  VDPRD 


The VDPRE macro is used to read one byte of data from the 
n 


VDF into the most significant byte of a register. Tuo  VDPRD 
macros cannot be used without other code between them or the 
accasses will be too fast for the YDP. 
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S.ii CALL Extended Utilities 

4 macro is provided to call utilities built into the ROM of 
the 0974 console and the ROMs in Extended BASIC. The syntax and 
ads generated ars: 


BLWP 2XMLLNA 
DATA <routine-name> 


The SCAN macra scans the 99/4 keyboard. The protocol is 
identical to the GPL SCAN instruction. The GPL status bit may be 
tested on return with a compare ones corresponding (COC) 
instruction 


3.123 SOUND 


The SOUND macro can be used to set up for the execution of 
au£2—-sound. The sound list, as described in the "GPL 
Programmer’s Guide", must be placed somewhere in VDP RAM. The 
VDF RAM address must be on a word boundary, ie. an even value, 
and must be in the register used in the macro. In addition the 
usa of this macro requires that the program contain the one byte 
value >01 at the label "CO1"'. This code does not actually start 
the  auto-sound. It simply initializes all the necessary memory 
locations. Auto-sound is driven by the VDP interrupt, therefore, 
the sound list will not begin executing until the interrupt is 
turned on. 


$.i4 ERROR 
The ERROR may be used to report errors and warnings. If it 
becomes necessary for an ALC program to return to BASIC with an 


error condition, the program may use the following macro in place 
of the normal return. 


ERROR symbol or value- 
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SECTION & 
Development 


The assembly language support will be developed using the 


GPL debugger hardware. This causes some difficulties since the 
debugger preempts RAM expansion at address 72000->3FFF. That 
space is used bg code and RAM memory for debug purposes. To 
avoid this problem the ALC support will be developed using RAM at 
>EIOO=-FFFFF. To achieve this Extended EASIC will be patched (in 
GROM: to only use 12K of the 244 RAM block. Then BASIC will use 
TACOO-LDFFF for program and data storage and 2EOOC--FFFF for ALC 
support. Reassemblg for EGROM will change the appropriate 
equates to use the correct address. The debugger EPROMS will be 


changed so that the XML table at >2C00 will be moved to >EOOO. 


Breakpoint capability for assembly language is being added 
fo the debugger to support testing the ALC support and for use 
during ALC development. 


Ang ALC coda developed on the debugger will run at a 
different address than in the real machine dye the reasons 
mentioned above. For relocatable code (the recommended way) this 
should be transparent when the code is written. 
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7.1 PEEK and POKE 

The LOAD statement supports the equivalent of a POKE 
function {direct memory load). The values PEEKed or POMEed are 
one byte values in the range Q to 255. Larger values are put in 
this range >1. 255=0, 257=1 ...}, provided they do not exceed 
the range 2767 to -32768 I? the address for PEEK or POKE. or 
the data for POXE is a floating point value than it 18 rounded. 
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SECTION 3 


Errors 

No new error messages were added for INIT, LOAD, or LINK 

Mil of the error messages issued are from Extended Basic. This 

saction lists the causes of errors for INIT, LOAD, and LINK that 
ara unique to assembly language support 


i. Syntax Error 


a. Expansion Ram not present 


LOAD 


Uu 
fu 


i. Syntax Error 


a. INIT has not been called 


2. Numeric Overflow 
a. Address of PORE out of range +32767 to -32763 
b. Data not in range 
22767 to -32788 
3. Unrecognized Character 
a. Invalid tag field 
4. Data Error 
a. Check Sum error when reading file 
$. Memory Full 


a. Not enough memory to load relocatable code into 
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a. #02 - File not found or is not a data file. 
b. #25 - File is not Sequential. Display, Fixed 80. 
LINK 


Dad Argument 
a. First paramater is not a string or is null. 
b. First parameter 13 greater than & characters. 
c. More than ió parameters 
PEEA 
Syntax Error 
a. Constant in parameter list, other than as the 
address. 
String Number Mismatch 
a. String argument in parameter list. 
Numeric Overflow 
a. Address is out of range 
Instruments e-2 PRELIMINARY 


ERAM. 
b. Not enough memory for entry table. 


I/2 Errors 


Syntax Error 
a. INIT has not been called 
Subprogram Mot Found 


a. Entry name in call to LINK not found. 


tJ 


00 


pa 


m 


6) 


n 
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3.5 NUMASG, STRAZG, NUMREF, STRREF 


String Number Mismatch 


rA 


a. Requested argument is not the proper type (string 
vs. numeric}. 


y 


Bad Argument 


a. Attempt to do an assignment to an expression 
instead of a variable. 


b. Array element number (RO is non-zero value when 
doing sn assignment or reference with a simple, 
iE. non-array, argument. 

c. Argument number (Ri) is zero 


d. Argument number (R1) exceeds number of arguments. 


Bad Subscript 


6 


a. Array element number (RO! is zero when OPTION 
BASE is 1. 


b. Array element number (RO) exceeds number of array 
elements. 


c. Bad dimension information found in symbol table. 
4. String Truncated 


a. In using STRREF, the referenced string exceeds 
the length of the provided buffer 
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APPENDIX A 


Macro Defirition F 
This appendix lists the text of the fil 
in an assembly language program (using tha 
de£zine the macros discussed in an earlier s 


4 


et (b 


sat should be included 
COPY directiva) to 
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+ 

+ MACROS FOR ALC SUPPORT 
4 

EGUDEB $MACRO 

ON EGU i 

OFF EGU 0 


DEBUG EGU ON 
VEPWA EQU. 2E8CO2 
VDFWD EGU  28COO 
VDPRD EGU  2£800 
vDPZTÀ EQU 28802 
FAC EQU 28344 
SUBWS BSS 2 
GPLWS EQU  2ES3EOC 
+ 

+ utility branches 
+ 

NUMASG EGU  >E008 
NUMREF EQU.  2EOCOC 
STRASG EQU 7560 
STRREF EQU  2EO14 
XMLLNK EQU 08 
KSCAN EGU "س٣16٤‎ 
VSEW EQU >EOSO 
VIEW EQU E024 
USER EQU <8 
VMER EGU  ^EOZC 
VWTR EQU  >ECIO 
ERR EGU >E034 
FADD EQU HODE4 
FSUB EGU  2O0DEO 
FMUL EQU  »OEEC 
FDIV EQU 21038 
SACD EQU 86 
SSUE EGU ODDS 
SMUL EQU ص۵‎ 
srry EQU 103€ 
cS EGU 12ي‎ 
CFI EQU  2131C 
FCOMF EQU <0 ٤عج‎ 
NEXT EQU  >008E 
COMPCT EGU >00 
GETSTR EQU >02 
MEMCHK EGU 704 
CNS EGU 204 
VPUSH EGU ZOE 
VP IOP EGU >10 
ASSGNV EGU >18 
CIF EQU >e 
SCROLL EQU 726 
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EQU. >34 
EQU 7326 
SEND 


$MACRÜ 
EQU 1 
ESGU QQ 
Eau Û 
Eau  28coa3 
EGU  28COO 
EGU 78800 
EGU 788502 
EQU 28244 
BSS 32 


EQU  -S3EO 
utility branches 


EGY 22008 
EGU  »200C 
EGU 72010 
EQU  >2014 
EGU 22018 
EGU  >201C 
EGU 32020 
EQU >2024 
EGU 72028 
EGU >202C 
EQU 22030 
EQU 722034 
EQU | 20D80 
EQU  20D7C 
EQU  20EBE 


EQU  2OFF4 
EGU 004 
EQU ۔‎ 4 
EQU FCEEC 
EQU >0FFE 
EQU  >114E 
EQU  712B8 
EQU ۸ی ۔‎ 
EQU 20070 
EQU >00 
EQU >02 
EQU >04 
EQU >06 
EQU ZOE 
EGU >10 
EQU 718 


EQU 0د‎ 
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VGWITE 
GVWITE 


+ 

EIUS 
DN 

OFF 

DE SUG 
VEPWA 
VIPWE 
VDPRE 
vDPSTA 
FAC 
SUEWS 
GPLWS 
4 

+ 

+ 
NUMASG 
NUMREF 
STRASG 
STRREF 
KMLUNK 
KSCAN 
VEBW 
VMEW 
VSER 
VMER 
VWTR 
ERR 
FADD 
FSUB 
FMUL 
60 
SADO 
بعحت‎ 
SMUL 
SCI 
CSN 
CFI 
FCOMP 
NEXT 
COMPCT 
GETSTR 
MEMCHK 
CNS 
VPUSH 
VPOP 
ASSGNV 
CIF 
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EQU 226 
EGU >34 
EGU ٤ 
$END 
MACRO 


ERROR EQUATES 


EGU 0200 2 Numeric Overflow 

EQU 20300 3 Syntax Error 

EQU 20400 4 Illegal after subprogram 
EQU 20500 5 Unmatched quotes 

EQU CSCO & Name too long 

EQU 20760 7 String-num mismatch 

EQU 20800 B Option base error 

EQU 20900 9 Improperly used name 
EQU 30400 10 Image error 

EGU  »0BOO 11 Memory full 

EQU  >0C00 12 Stack overflow 

EQU  20DOÓ 3 Next without for 

EQU 0 14 For next nesting 

EQU >OFOO 15 Must be in subprogram 
EGU 721000 16 Recursive subprogram call 
EGU 21100 7 Missing subend 

EQU 71200 18 Return without gosub 
EGU 271300 19 String truncated 

EGU 71400 20 Bad subscript 

EQU ISOC 21 Speech string too long 
EQU 71500 22 Line not found 

Equ 251700 23 Bad line number 

EGU  ۔:‎ 0 24 Line too long 

EGU 21900 25 Can t continue 

EQU 71400 24 Command illegal in program 
EGU 71806 27 Only legal in a program 
EGU 60ز‎ 28 Bad argument 

EQU 0ن‎ 29 No program present 

EQU 0ى‎ 30 Bad value 

EQU  -1FO0O0 31 Incorrect argument list 
EGU  »2000 32 Input error 

EQU 521060 23 Data error 

EQU  »2200 34 File error 

EGU  >2400 36 170 error 

EQU  »2500 37 Subprogram not found 
EQU +2700 29 Protection violation 
EQU >2800 4Q Unrecognized character 
EQU 22700 41 Numeric overflow 

EQU 22400 2 String truncated 

EQU  >2BC0 43 No program present 

EQU >2C00 44 Input error 

EQU  »2DOO 45 I/O error 
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SCROLL 
VGWITE 
GYWITE 


ERRSYN 
ERRIBS 
ERRNGS 
ERRNTL 
ERRSNM 
جع 6ع‎ 
ERRMUV 
ERRIM 
ERRMEM 
ERRSO 
ERRNWF 
ERRFNN 
ERRSNS 
ERRRSC 
ERRMS 
ERRRWG 
ERRST 
ERRBS 
ERRSSL 
ERRLNF 
ERRELN 
ERRLTL 
ERRCC 
ERRCIP 
ERROLP 
ERRADA 
ERRNPP 
ERRDW 
ERRIAL 
ERR IMP 
ERRDAT 
ERRFE 
ERRIO 
66 6۶۳ 
ERRPY 
ERRIVN 
WR NR) 
WRNST 
WRNNPP 
WRNINP 
WRNIO 
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EGU >2E00 ig Line not found 

SEND 

SMACRO 

DEF  VDPUA, VDPWD, VEPRD, VDPSTA, FAC, SUBWS, GPLWS 
DEF  NUMASG, NUMREF, STRASG, STRREF, XMLLNK, KSCAN 
DEF  VS€BW, VMEW, ۷/58 ج‎ , VMBR, VWTR, ERR, FADD 

DEF FSUB, FMUL, FDIV; ZADD, SEUB, SMUL, ED IV, CSN 
DEF  CFI,FCQMP,NEXT, COMPCT, GETSTR, MEMCHK, VPUSH 
DEF  ASZGNV, CNS, VPOP. CIF, SCROLL, VGWITE, GVWITE 
SEND 

$MACRO 

REF VDPWA: /DPWD, VDFRD. VDFSTA, FAC, SUBWS, GPLWS 
REF  NUMASG, NUMREF, STRASG, STRREF, XMLLNK, KSCAN 
REF 807ب‎ VMEW, VSBR, VMBR, VWTR, ERR, FADD 

REF  FSUB, FMUL. FDIV, SADD, 08ا2‎ SMUL., SDIV, CSN 
REF  CFI,FCOMP, NEXT. COMPCT, GETSTR, MEMCHK, VPUSH 
REF ASSGNY. CNS, VPOP. CIF, SCROLL, VGWITE, GVWITE 
$END : 

SMACRO Pi 

DEF : Pi 

LWPI SUBWS 

$END 

$MACRO 

SZCB 80209 ٤۳ 

LWPI GPLWS 

B QNEXT 

$END 

$MACRO P1 

SWPB : Pi 

MOVB :P1:, @VDPWA 

SWPB : Pi 

MOVB :P1:, @VDPWA 

SEND 

SMACRO Pi 

MOVB :P1:, SVvDPWD 

$END 

$MACRO P1 

MOVB GVDPRD,: Pi 

SEND 

$MACRO Pi 

BLWP @XMLLNK 

DATA 1 
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4 
RETURN 


+ 
0۳ب 


+ 
VDPWD 


+ 
VDPRD 


+ 
CALL 
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SEND 


SCAN $MACRO 


BLWP @KSCAN 


SEND 


+ 

SOUND MACRO Pi 
MOV  :P1:: 
SOCE ecol, 
MOVB 1۱۰ 
$END 

* 

ERROR S$MACRO P1 


L1 RO, :P1 


BLWP ٤8 
$END 
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